WARNING: USE "MACINI" AT YOUR OWN RISK!!! THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR ASSUMES NO RESPONSIBILTY FOR THE PERFORMANCE OR RELIABILITY OF THIS SOFTWARE OR ITS ACCOMPANYING DOCUMENTATION!!!
Revision History
This file accompanies version 1.30 of the MacINI product.
MacINI 1.30
Released 10/31/95, incorporated the following changes:
1) Changed every occurance of the type "int" to the type "long" (in both function returns and function parameters) to ensure compatibility with compilers which do not use 4-byte ints by default. (Thanks to Rob Thorne at Aladdin Systems for the suggestion).
2) Added code to prevent writing of the leading blank line in cases where the WritePreferenceString must create a new preferences (.INI) file because none previously existed.
3) Made minor changes to make the code smaller (faster?) and less "quick and dirty".
MacINI 1.20
Released 9/18/95, incorporated the following changes:
1) Memory leaks were found and removed. In version 1.10 and earlier, MacINI failed to release a buffer it allocated, thereby creating a memory leak. (Thanks to Robert Kuchera for pointing out this bug).
2) MacINI is supposed to create a new preferences file if the "WritePreferenceString" routine is called and passed the file specification for a file that does not exist. A bug in MacINI 1.10 and earlier versions prevented this from working. This has now been remedied.
Intro
The "MacINI" project began when the author, developing a common application to be run on both Apple Macintosh and Microsoft Windows platforms, determined that it would be desirable to use the same configuration files across the two platforms.
While Microsoft Windows has standardized on the ".ini" file as the recommended way of storing application-specific configuration information (Windows itself even uses such files), Apple has no such simplified standard for the resource-based "preferences" files most Macinstosh applications use. This inconvenience prompted me to write this quick and dirty set of routines to mimic the functionality of the Microsoft Windows API calls that pertain to the handling of private ".ini" files.
Since my routines are "quick and dirty", they are likely to be somewhat less robust than their Microsoft counterparts. However, I have more or less fully tested them and have removed all the major bugs. They even do a few things that Microsoft's routines can't (like handling negative integers). Anyway, MacINI is a tool for Macintosh developers, who by nature are wickedly smart and should easily be able to overcome any obstacles that might arise! It provides a simple, standard way for a developer to quickly implement a preferences file on the Macintosh using an ASCII text file, with the added advantage that these files can then be made platform independent.
There should be four files that accompany this document (however, I got lazy and only wrote two of them). The first file is the "MacINI.c.o" object file, and should be linked with your program when you build it. The second file is the "MacINI.h" header file, which contains the public interfaces for the three core routines in the "MacINI" project. Eventually will come the third file, "MacINI User's Guide", and the fourth, "MacINI Reference". If you want these, you'll have to REGISTER (see below).
The Basics
The format of the MacINI-generated configuration files adheres to the standard recommended by Microsoft for ".ini" files, where each line may be a "Section" name, an "Entry", or blank. This format is used by most Microsoft Windows applications.
A "section" name line takes the form "[SECTION]", and is not case-sensitive. An "entry" takes the form "ENTRY=SETTING", where "entry" is a text string that descibes the nature of the setting that follows. The ordering of entries (lines) within a given section is unimportant. A "setting" may be interpreted as a text strings, an integer, or a flag (Boolean value). Text strings may contain any printable ASCII character except these:
[ LEFT SQUARE BRACKET
] RIGHT SQUARE BRACKET
= EQUAL SIGN
Flags may only take on the values 0 (FALSE) or 1 (TRUE). Values other than these should be interpreted as TRUE also, as they are non-zero, but you shouldn't count on it!
The settings in a "MacINI"-compatible preferences file are read/written using routines called "GetPreferenceInt", "GetPreferenceString", and "WritePreferenceString". The functionality of these routines is similar, but not identical, to the functionality of the Microsoft Windows calls "GetPrivateProfileInt", "GetPrivateProfileString", and "WritePrivateProfileString". The maximum useable size of preferences files to be read by "MacINI" is 4096 bytes for this release. Data beyond that limit will be ignored.
It should be obvious that the "GetPreferenceInt" and "GetPreferenceString" routines simply search through the specified configuration file for the given ENTRY (expecting to return either an integer or a text string, respectively). It should also be obvious that the "WritePreferenceString" routine attempts to write the given ENTRY=SETTING line into the specified SECTION of the specified configuration file. What is important but not obvious is that these routines accept PASCAL STRINGS, whereas their Microsoft conterparts accept C strings. This should not present any problems for the typical developer, since many Macintosh toolbox routines also accept Pascal strings.
As with the Microsoft routines, if the specified file does not exist for read operations, default values will be used and no error will occur. For new files created by MacINI write operations, the Macintosh "file type" will be set to 'TEXT', and the "creator" signature to 'ttxt', so that the newly-created configuration file can be double-clicked to open and edit it using Apple's "TeachText" text processing utility. Important: If another editor is used, and that editor places any "hidden" characters in the file, the entries will not be recognized even though they may appear normally. In such cases, the file can be repaired by removing these hidden characters, or replaced from an original source.
For those interested, during write operations, MacINI initially creates a temporary file in the preferences folder. Then, after the temporary file has been completely written, it is swapped with the target ".INI" file also in the preferences folder. Finally, the temporary file is removed.
Until further documentation for the "MacINI" project becomes available, when in doubt, refer to the Microsoft Windows SDK for info regarding the three API calls that my three routines mimic, and you'll get the general idea of how my routines probably work (beware, there are differences).
Historical and Legal Notes
MacINI 1.10 is the first version to be released/unleashed on the public. Previous versions have been incorporated into in-house projects and seem to be working reliably.
The entire "MacINI" project has been written, tested (sorta), and produced by the author, James K. Toothman of Essential Technologies. This product is copyrighted by the author and all rights are reserved, except that it is intended to be distributed as FREEWARE, meaning you may redistribute it freely as long as you do not modify the contents of any of the files. You MAY NOT charge a fee for this product.
This product is backed by following no-nonsense lifetime guarantee:
• if you look long and hard enough, you WILL find bugs in this product.
• if you like this product, you can keep it and pay nothing.
• if you don't like this product, you can keep it and pay nothing.
It bears repeating that you must USE "MACINI" AT YOUR OWN RISK!!! THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR ASSUMES NO RESPONSIBILTY FOR THE PERFORMANCE OR RELIABILITY OF THIS SOFTWARE OR ITS ACCOMPANYING DOCUMENTATION!!!
Comments and/or questions regarding this product may be directed to:
James K. Toothman
Essential Technologies
54 Valley Road
Glen Rock, NJ 07452-1712
AOL: EssentialT
AppleLink: JT.ESSENTIAL
Prodigy: XTWM92F
Anyone wishing to do so may register with me by mail, and I will gladly provide additional FREE upgrades to this product if and when they become available (I expect at least one more enhanced version to be completed by 12/95). Please include your name, address, and a crispy, new $1.00 bill (to cover the cost of the diskette and mailing).
